/*
 * This code was written by Bear Giles <bgiles@coyotesong.com>and he
 * licenses this file to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance with the
 * License.  You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Any contributions made by others are licensed to this project under
 * one or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.
 * 
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 * 
 * Copyright (c) 2012 Bear Giles <bgiles@coyotesong.com>
 */
package com.invariantproperties.crypto.keyServer;

import java.security.Key;
import java.util.Date;

/**
 * Interface that defines methods that can be used to access keys. Keys can be
 * marked as 'encrypt-only' and 'decrypt-only' and there is a business case for
 * supporting this separation, namely security levels.
 * 
 * Security Levels
 * 
 * A widely used algorithm with multiple security levels (e.g., confidential,
 * secret and top secret) is that a user can read information at lower levels
 * but not write it. Likewise the user can write information at higher levels
 * but not read it.
 * 
 * Design note: keys can be marked as for encryption only or decryption only.
 * 
 * Design note: the interface uses 'Key' but I'm not sure whether keys can be
 * serialized. The interface signatures may have to change as implementation
 * uncovers information.
 * 
 * @author bgiles@coyotesong.com
 */
public interface KeyService {
    /**
     * Get an encryption key.
     */
    Key getEncryptionKey(int keyid, KeyServiceAuthenticationInfo auth);

    /**
     * Get a decryption key.
     */
    Key getDecryptionKey(int keyid, KeyServiceAuthenticationInfo auth);

    /**
     * Generate a new encryption key. TODO: add usage flags?
     */
    int generateKey(Key key, Date notBefore, Date notAfter,
            KeyServiceAuthenticationInfo auth);
}
